Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 8 - Printing

Handling Printing Dialog Boxes

This programming recipe shows you how to prepare for, display, and respond to each of the three printing dialog boxes:

• the Print dialog box
• the Page Setup dialog box
• the Custom Page Setup dialog box

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Install a printing message handler
2. Disable menu items
3. Prepare an edit menu structure
4. Handle the Print dialog box
5. Handle the Page Setup dialog box
6. Handle the Custom Page Setup dialog box

You need to follow all of the steps in this recipe for any application that allows custom page formatting.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXInstallApplicationOverride	"Core Printing Features" QuickDraw GX Printing
GXJobPrintDialog	"Core Printing Features" QuickDraw GX Printing
GXGetJobError	"Core Printing Features" QuickDraw GX Printing
GXJobDefaultFormatDialog	"Core Printing Features" QuickDraw GX Printing
GXFormatDialog	"Page Formatting and Dialog Box Customization" QuickDraw GX Printing
GXNewFormat	"Page Formatting and Dialog Box Customization" QuickDraw GX Printing
GXDisposeFormat	"Page Formatting and Dialog Box Customization" QuickDraw GX Printing

Standard Macintosh functions used in this recipe:

DisableItem	"Menu Manager" Macintosh Toolbox Essentials
EnableItem	"Menu Manager" Macintosh Toolbox Essentials

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

Recipe Step Descriptions

In this section, each step is described individually.

1. Install a printing message handler

   With QuickDraw GX, the user can move the printing dialog boxes to display information on the screen that might be obscured by them. Therefore, your application might need to update its windows whenever the user moves a printing dialog box. However, since the printing dialog boxes are modal, your application doesn't receive events while a printing dialog box is displayed--only QuickDraw GX receives the events.

   Fortunately, QuickDraw GX provides a mechanism that solves this problem. You can create a function that handles events while a printing dialog box is displayed and requests that QuickDraw GX call your function when the user moves one of the printing dialog boxes.

   Here is a sample function you can use to handle events while a printing dialog box is displayed:

   OSErr MyPrintingEventHandler(EventRecord *anEvent, 
                              Boolean filterEvent)
   {
       if (!filterEvent)
           switch (anEvent->what) {
               case mouseDown:
               case keyDown:
               case autoKey:
                   break;
               default:
                   MyHandleEvent(anEvent);
           }
       return(noErr);
   }

   With this function, your application does nothing if the event is a mouse down, key-down, or auto-key event, since your application shouldn't handle those types of events when a printing dialog box is displayed. You can add other types of events you don't want to handle to this list.

   If the event is a type of event that you should handle while a printing
   dialog box is displayed (for example, an update event), you call your application's main event-handling function, which is named MyHandleEvent in the example.

   Once you've defined the function that handles the events, you need to request that QuickDraw GX call this function when the user moves a printing dialog box. This process is called installing a message handler.
   You use the GXInstallApplicationOverride function to install your message handler.

   GXInstallApplicationOverride(gCurrent->documentJob,
                                gxPrintingEvent,
                                PrintingEventHandler);

2. Disable menu items

   Before you display any of the printing dialog boxes, you need to disable menu items that you don't want the user to choose while the dialog box is displayed. As a general rule you want to disable all of your menus, except:

   • the Edit menu, which QuickDraw GX uses
   • the Apple menu (although you should disable your application's About menu item)

     You can use the standard Macintosh function DisableItem to disable whole menus as well as menu items.

     When you are finished displaying the printing dialog box, you should use the standard Macintosh function EnableItem to enable the menus you disabled.

3. Prepare an edit menu structure

   QuickDraw GX supports basic editing commands when a printing dialog box is displayed. The user can choose the Cut, Copy, Paste, Clear, and Undo commands while a printing dialog box is active, using your application's Edit menu. To handle these menu items, QuickDraw GX needs to know the menu ID of your Edit menu and the location within the Edit menu of these menu items. You specify this information to QuickDraw GX using an edit menu structure:

   struct gxEditMenuRecord {
       short editMenuID;
       short cutItem;
       short copyItem;
       short pasteItem;
       short clearItem;
       short undoItem;
   }

   You prepare an edit menu structure before calling any of the QuickDraw GX functions that display a printing dialog box. When you display one, you provide QuickDraw GX with a pointer to your structure.

4. Handle the Print dialog box

   To display the Print dialog box, you call the GXJobPrintDialog function. You should always call the GXGetJobError function immediately after calling the GXJobPrintDialog function to check for errors. You can use this code to display the Print dialog box:

   OSErr err;
   gxDialogResult result;

   result = GXJobPrintDialog(gCurrent->documentJob,
                             &gMyEditMenuStructure);

   err = GXGetJobError(gCurrent->documentJob);

   if ((err == noErr) && (result == gxOKSelected))
       err = PrintDocument(gCurrent);
   else {
       /* Code to handle errors goes here. */
   }

   The GXJobPrintDialog function returns the constant gxOKSelected if the user closed the dialog box by clicking the OK button, indicating that your application should start printing. The recipe "Printing a Document With Custom Formats," beginning on page 264, shows how to do this.

5. Handle the Page Setup dialog box

   You display the Page Setup dialog box in much the same way that you display the Print dialog box, except you use the GXJobDefaultFormatDialog function:

   OSErr err;
   gxDialogResult result;

   result = GXJobDefaultFormatDialog(gCurrent->documentJob,
                                     &gMyEditMenuStructure);

   err = GXGetJobError(gCurrent->documentJob);

   if ((err == noErr) && (result == gxOKSelected))
       /* Code to repaginate the document goes here. */
   else {
       /* Code to handle errors goes here. */
   }

   The purpose of the Page Setup dialog box is to allow the user to change the default page-formatting information for a document. If the user closes the Page Setup dialog box by clicking the OK button, the default format object for your current document job might have changed. Therefore, you should examine the new default page format and repaginate your document accordingly.

6. Handle the Custom Page Setup dialog box

   The Custom Page Setup dialog box allows the user to specify a custom page format for the page in your document currently being viewed.

   If the current page already has a custom format object, you copy the reference to that format object into the local variable pageFormat. If not,
   you create a new page format object using the GXNewFormat function:

   gxFormat pageFormat;
   Boolean newPageFormat = false;

   if (gCurrent->pageFormat[gCurrent->curPage-1] != nil)
      pageFormat = gCurrent->pageFormat[gCurrent->curPage-1];
   else {
      pageFormat = GXNewFormat(gCurrent->documentJob);
      err = GXGetJobError(gCurrent->documentJob);
      newPageFormat = true;
   }

   If any errors result from the GXNewFormat function, QuickDraw GX stores them in the job object. You can retrieve the error code from the job object using the GXGetJobError function:

   OSErr err;

   err = GXGetJobError(gCurrent->documentJob);

   If no error resulted, you can display the Custom Page Format dialog box using the GXFormatDialog function:

   gxDialogResult result;

   if (err == noErr) {

      result = GXFormatDialog(pageFormat, &gMyEditMenuStructure,
                              nil);

      switch (result) {
        case okSelected:
           gCurrent->pageFormat[gCurrent->curPage-1] = pageFormat;
           break;

        case revertSelected:
           GXDisposeFormat(pageFormat);
           gCurrent->pageFormat[gCurrent->curPage-1] = nil;
           break;

        case cancelSelected:
           if (newPageFormat)
              GXDisposeFormat(pageFormat);
           break;
      }
   }

   If the user closed the dialog box by clicking the OK button, your application records the user's choice by storing a reference to the custom format object in the pageFormat array of the document information record.

   If the user closed the dialog box by clicking the Remove button, your application disposes of the format object for the current page and sets
   the corresponding entry in the pageFormat array to nil.

   If the user canceled the dialog box, your application does nothing except dispose of the new format object if it created one.

Related Recipes

For more information about printing with QuickDraw GX, see these recipes:

• "Managing Printing Information," beginning on page 253, shows how to create and dispose of job objects.
• "Printing a Document With Custom Formats," described next, shows how to print a document.
• "Saving Printing Information," beginning on page 267, shows how to save a job object.

The recipes in Chapter 4, "Using the QuickDraw GX Environment," show you how to initialize QuickDraw GX printing. You should read the recipes in that chapter before using the recipes in this chapter.